Documentation: testing_plans / Testing Plan

1. C++ Pybindings Validation (GTest & Pytest):
Test Cases:
test_safe_assign_binding_integrity: Pass Boolean, Integer, and Enum string types from Python dictionaries into C++ hexa::RunConfig via Pybind11.
TestManifestBridge: Validate C++ hexa::CompilationResult properties correctly reflect into Python ManifestModel schema.
ConfigSafetyTest.HandlesMalformedJSONInjection: Inject deeply nested or malformed JSON payloads into RunConfig::from_json.
Expected Outcomes:
  • C++ layer extracts Python variables without segmentation faults.
  • Type mismatches or overflows trigger controlled fallbacks or raise caught std::invalid_argument exceptions passed back to Python. Manifest generation strictly enforces mandatory fields.
Verification Methods:
  • Pytest assertions on data type mapping (isinstance</code>).
  • GTest EXPECT_NO_THROW and EXPECT_EQ ensuring safe fallback values (e.g., SEEDLESS_VALUE).
2. Class Object Integrity (C++, Python, TypeScript):
Test Cases:
C++ Core: OptimizerLogicTest for dead code elimination and constant foldingLinearizerTest - LinearizerTest for nested math AST translationVMTest - VMTest for memory bound checks (HighRegisterPressure), loop termination, and stack underflow logic.
Python Backend: TestOracle and HexaASTSerializer for validating accurate translation of native Python ast nodes to JSON.
TypeScript Frontend:
  • BaseCRUD memento pattern tests (isDirty flag logic).
  • BaseLibrary collection hydration.
Expected Outcomes:
  • Optimizer reduces AST complexity without altering deterministic output.
  • VM halts predictably on stack underflow or type mismatch (ThrowsOnTypeMismatch).
  • TS models track local state mutations and revert cleanly.
Verification Methods:
  • GTest executing bytecode and validating literal extraction (get_double).
  • Pytest validating dictionary structure of serialized AST.
  • Vitest verifying Svelte $state reactivity and dirty flags.
3. Backend Endpoint & Pydantic Structure Validation:
Test Cases:
TestCompilerConfigDynamicOrchestration: Verify FastAPI endpoint schema matches the dynamically generated C++ SchemaBuilder payload.
test_dispatch_pipeline_success: Post CommandPayload to /api/dispatch triggering database entry and background worker queue.
TestCompileJobOrchestration: Validate DB integrity and cascading foreign keys across AST, CompilerConfig, and CompileJob.
Expected Outcomes:
  • API endpoints correctly enforce BatchConfig and CommandPayload Pydantic contracts.
  • Missing required fields yield 422 Unprocessable Entity.
  • Authorized requests insert SQLite records and spawn multiprocessing tasks successfully.
Verification Methods:
  • Pytest TestClient executing HTTP requests.
  • SQLAlchemy inspect(CompilerConfig) asserting exact column parity with C++ configuration definitions.
4. Frontend Data Dispatch Accuracy:
Test Cases:
BaseCRUD.Validation: Pass invalid/incomplete forms into TS model before dispatch.
getValidPayload: Verify stripping of UI-only properties (e.g., isEditing) before network transmission.
Expected Outcomes:
  • Zod schemas intercept malformed data client-side, throwing ValidationError and halting fetch.
  • Generated payloads strictly match the backend's expected JSON format.
Verification Methods:
  • Vitest expect(() => getValidPayload(true)).toThrow(). Spying on internal apiFetch calls to assert the shape of the intercepted HTTP body.
5. End-to-End API Integration & Telemetry Synchronization:
Test Cases:
runIntegrationSuite: Execute chained sequence creating ResearchTier -> LLMServer -> Prompt LLMModel -> PromptConfig.
FullChainTest: Inject Python AST payload, execute compiler pass, and await trace result.
Expected Outcomes:
  • System maintains state synchronization across the network boundary.
  • C++ execution yields physical .hex and .meta.json files.
  • Database accurately links execution Manifest to the original CompileJob.
  • WebSocket/Polling loops hydrate the UI RegisterGrid and ASTViewer with zero data mutation.
Verification Methods:
  • Vitest polling tests resolving simulated backend responses.
  • GTest fs::exists verifying absolute file paths of generated artifacts in the scoped temporary workspace.